<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>Getting started with Wonderful Toolchain | Butano Docs</title>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
  <link rel="icon" href="favicon-dark.png" type="image/png" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <meta name="theme-color" content="#22272e" />
</head>
<body>
<header><nav id="navigation">
  <div class="m-container">
    <div class="m-row">
      <span id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">
        <a href="https://github.com/GValiente/butano">Butano</a> <span class="m-breadcrumb">|</span> <a href="index.html" class="m-thin">Docs</a>
      </span>
      <div class="m-col-t-4 m-hide-m m-text-right m-nopadr">
        <a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
          <path id="m-doc-search-icon-path" d="m6 0c-3.31 0-6 2.69-6 6 0 3.31 2.69 6 6 6 1.49 0 2.85-0.541 3.89-1.44-0.0164 0.338 0.147 0.759 0.5 1.15l3.22 3.79c0.552 0.614 1.45 0.665 2 0.115 0.55-0.55 0.499-1.45-0.115-2l-3.79-3.22c-0.392-0.353-0.812-0.515-1.15-0.5 0.895-1.05 1.44-2.41 1.44-3.89 0-3.31-2.69-6-6-6zm0 1.56a4.44 4.44 0 0 1 4.44 4.44 4.44 4.44 0 0 1-4.44 4.44 4.44 4.44 0 0 1-4.44-4.44 4.44 4.44 0 0 1 4.44-4.44z"/>
        </svg></a>
        <a id="m-navbar-show" href="#navigation" title="Show navigation"></a>
        <a id="m-navbar-hide" href="#" title="Hide navigation"></a>
      </div>
      <div id="m-navbar-collapse" class="m-col-t-12 m-show-m m-col-m-none m-right-m">
        <div class="m-row">
          <ol class="m-col-t-6 m-col-m-none">
            <li><a href="pages.html">Pages</a></li>
            <li><a href="modules.html">Modules</a></li>
          </ol>
          <ol class="m-col-t-6 m-col-m-none" start="3">
            <li><a href="namespaces.html">Namespaces</a></li>
            <li><a href="annotated.html">Classes</a></li>
            <li><a href="files.html">Files</a></li>
            <li class="m-show-m"><a href="#search" class="m-doc-search-icon" title="Search" onclick="return showSearch()"><svg style="height: 0.9rem;" viewBox="0 0 16 16">
              <use href="#m-doc-search-icon-path" />
            </svg></a></li>
          </ol>
        </div>
      </div>
    </div>
  </div>
</nav></header>
<main><article>
  <div class="m-container m-container-inflatable">
    <div class="m-row">
      <div class="m-col-l-10 m-push-l-1">
        <h1>
          Getting started with Wonderful Toolchain
        </h1>
        <nav class="m-block m-default">
          <h3>Contents</h3>
          <ul>
            <li><a href="#getting_started_wt_supported_platforms">Supported platforms</a></li>
            <li><a href="#getting_started_wt_emulator">GBA emulator</a></li>
            <li><a href="#getting_started_wt_wt">Wonderful Toolchain</a></li>
            <li><a href="#getting_started_wt_python">Python</a></li>
            <li><a href="#getting_started_wt_butano">Butano</a></li>
            <li><a href="#getting_started_wt_examples">Butano examples</a></li>
            <li><a href="#getting_started_wt_template">Make your own GBA game!</a></li>
          </ul>
        </nav>
<p>Downloading Butano and building their games and examples is easy and doesn&#x27;t take too much time, pinky promise.</p><section id="getting_started_wt_supported_platforms"><h2><a href="#getting_started_wt_supported_platforms">Supported platforms</a></h2><p><a href="https://wonderful.asie.pl/">Wonderful Toolchain</a> supports Windows and Unix-like platforms.</p><p>If you want to develop on macOS, you should try to use a Linux virtual machine or <a href="getting_started.html" class="m-doc">devkitARM</a> instead.</p></section><section id="getting_started_wt_emulator"><h2><a href="#getting_started_wt_emulator">GBA emulator</a></h2><p>Before anything, it is convenient to have a GBA emulator at hand, so you don&#x27;t have to test in real hardware each change you make in your project.</p><p>For developing GBA games, <a href="https://mgba.io">mGBA</a>, <a href="https://github.com/nba-emu/NanoBoyAdvance">NanoBoyAdvance</a>, <a href="https://github.com/SourMesen/Mesen2">Mesen</a> and the debug version of <a href="https://problemkaputt.de/gba.htm">No$gba</a> are recommended.</p></section><section id="getting_started_wt_wt"><h2><a href="#getting_started_wt_wt">Wonderful Toolchain</a></h2><p>The next step is to download and install <a href="https://wonderful.asie.pl/">Wonderful Toolchain</a> using <a href="https://wonderful.asie.pl/docs/getting-started/">this tutorial</a>.</p><p>From now on, this guide assumes a Windows environment, but the steps to take for Unix-like platforms should be similar.</p><img class="m-image" src="wt_installer.png" alt="Image" /><p>Once installed, open the Wonderful Toolchain Shell and run the following commands, accepting the default options when prompted:</p><pre class="m-code"><span class="n">pacman</span><span class="w"> </span><span class="o">-</span><span class="n">S</span><span class="w"> </span><span class="n">make</span>
<span class="n">wf</span><span class="o">-</span><span class="n">pacman</span><span class="w"> </span><span class="o">-</span><span class="n">Syu</span><span class="w"> </span><span class="n">wf</span><span class="o">-</span><span class="n">tools</span>
<span class="n">wf</span><span class="o">-</span><span class="n">pacman</span><span class="w"> </span><span class="o">-</span><span class="n">Syu</span><span class="w"> </span><span class="n">wf</span><span class="o">-</span><span class="n">tools</span>
<span class="n">wf</span><span class="o">-</span><span class="n">config</span><span class="w"> </span><span class="n">repo</span><span class="w"> </span><span class="n">enable</span><span class="w"> </span><span class="n">blocksds</span>
<span class="n">wf</span><span class="o">-</span><span class="n">pacman</span><span class="w"> </span><span class="o">-</span><span class="n">Syu</span>
<span class="n">wf</span><span class="o">-</span><span class="n">pacman</span><span class="w"> </span><span class="o">-</span><span class="n">S</span><span class="w"> </span><span class="n">target</span><span class="o">-</span><span class="n">gba</span>
<span class="n">wf</span><span class="o">-</span><span class="n">pacman</span><span class="w"> </span><span class="o">-</span><span class="n">S</span><span class="w"> </span><span class="n">blocksds</span><span class="o">-</span><span class="n">toolchain</span></pre><img class="m-image" src="wt_pacman.png" alt="Image" /></section><section id="getting_started_wt_python"><h2><a href="#getting_started_wt_python">Python</a></h2><p>To execute some of the tools needed to include image and audio files in your project, you are going to need <a href="https://www.python.org/">Python</a>.</p><p>If you are going to install Python on Windows, remember to add it to the <code>PATH</code> and to close all system console windows before installing it:</p><img class="m-image" src="python_windows.png" alt="Image" /><p>Both Python 2 and Python 3 are supported for now, but Python 2 is not going to be supported for too long. Make sure you can execute Python from the Wonderful Toolchain Shell:</p><img class="m-image" src="wt_python.png" alt="Image" /><p>If you have an Ubuntu/Debian based system with <code>python3</code> instead of <code>python</code>, you can:</p><ul><li>Specify <code>python3</code> as the Python interpreter path in the <code>Makefile</code> of the project you are trying to build.</li><li>Install <code>python-is-python3</code>: <code>sudo apt-get install python-is-python3</code>.</li></ul></section><section id="getting_started_wt_butano"><h2><a href="#getting_started_wt_butano">Butano</a></h2><p>Download or clone the latest Butano release from <a href="https://github.com/GValiente/butano">GitHub</a> and put it in a path without spaces or anything weird, please.</p></section><section id="getting_started_wt_examples"><h2><a href="#getting_started_wt_examples">Butano examples</a></h2><p>Butano contains multiple <a href="examples.html" class="m-doc">examples</a> of most aspects of the engine.</p><p>Make sure that you are able to build and run some of them:</p><ul><li>They are located in <code>/path/to/butano/examples/</code>.</li><li>To build a Butano example, open the Wonderful Toolchain Shell, <code>cd</code> to the folder of the example you want to build and type <code>make -j8</code> if your CPU has 8 cores, <code>make -j16</code> if it has 16 and so on.</li></ul><img class="m-image" src="wt_example_1.png" alt="Image" /><p>When trying to build the <code>sprites</code> example, if everything went as expected, a <code>sprites.gba</code> file should have been generated in the <code>sprites</code> folder, and the system console should show something like this:</p><img class="m-image" src="wt_example_2.png" alt="Image" /></section><section id="getting_started_wt_template"><h2><a href="#getting_started_wt_template">Make your own GBA game!</a></h2><p>If you were able to build and run some examples, congrats! Now you can make your own GBA game with Butano. To do that:</p><ul><li>Copy the template project located in <code>/path/to/butano/template/</code> to a path without spaces or weird characters.</li><li>Change in the <code>Makefile</code> the path in which Butano library folder is located. For example, if Butano is located in <code>/path/to/butano/</code>, <code>LIBBUTANO</code> variable should be set to <code>/path/to/butano/butano</code>.</li><li>If you want, you can also change ROM title, ROM code and more in the <code>Makefile</code>.</li><li><code>cd</code> to the new folder.</li><li>Type <code>make -j#cpu_cores#</code> again.</li></ul><p>If everything went as expected, a <code>*.gba</code> file should have been generated in the project folder!</p><p>Now learn how to <a href="import.html" class="m-doc">import your assets</a> in the game and also take a look at the <a href="modules.html">modules</a> page. It&#x27;s always a good idea to play around with the examples as they cover most of what Butano offers. The <a href="faq.html" class="m-doc">frequently asked questions (FAQ)</a> are worth a look too, as they answer most of the initial questions.</p></section>
      </div>
    </div>
  </div>
</article></main>
<div class="m-doc-search" id="search">
  <a href="#!" onclick="return hideSearch()"></a>
  <div class="m-container">
    <div class="m-row">
      <div class="m-col-m-8 m-push-m-2">
        <div class="m-doc-search-header m-text m-small">
          <div><span class="m-label m-default">Tab</span> / <span class="m-label m-default">T</span> to search, <span class="m-label m-default">Esc</span> to close</div>
          <div id="search-symbolcount">&hellip;</div>
        </div>
        <div class="m-doc-search-content">
          <form>
            <input type="search" name="q" id="search-input" placeholder="Loading &hellip;" disabled="disabled" autofocus="autofocus" autocomplete="off" spellcheck="false" />
          </form>
          <noscript class="m-text m-danger m-text-center">Unlike everything else in the docs, the search functionality <em>requires</em> JavaScript.</noscript>
          <div id="search-help" class="m-text m-dim m-text-center">
            <p class="m-noindent">Search for symbols, directories, files, pages or
            modules. You can omit any prefix from the symbol or file path; adding a
            <code>:</code> or <code>/</code> suffix lists all members of given symbol or
            directory.</p>
            <p class="m-noindent">Use <span class="m-label m-dim">&darr;</span>
            / <span class="m-label m-dim">&uarr;</span> to navigate through the list,
            <span class="m-label m-dim">Enter</span> to go.
            <span class="m-label m-dim">Tab</span> autocompletes common prefix, you can
            copy a link to the result using <span class="m-label m-dim">⌘</span>
            <span class="m-label m-dim">L</span> while <span class="m-label m-dim">⌘</span>
            <span class="m-label m-dim">M</span> produces a Markdown link.</p>
          </div>
          <div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>
          <ul id="search-results"></ul>
        </div>
      </div>
    </div>
  </div>
</div>
<script src="search-v2.js"></script>
<script src="searchdata-v2.js" async="async"></script>
<footer><nav>
  <div class="m-container">
    <div class="m-row">
      <div class="m-col-l-10 m-push-l-1">
        <p>Butano Docs. Created with <a href="https://doxygen.org/">Doxygen</a> 1.14.0 and <a href="https://mcss.mosra.cz/">m.css</a>.</p>
      </div>
    </div>
  </div>
</nav></footer>
</body>
</html>
